<html>
<head>
<title>JP2ECW -- ERDAS JPEG2000 (.jp2)</title>
</head>

<body bgcolor="#ffffff">

<h1>JP2ECW -- ERDAS JPEG2000 (.jp2)</h1>

GDAL supports reading and writing JPEG2000 files using the ECW SDK from 
ERDAS.<p>

Coordinate system and georeferencing transformations are read, and 
some degree of support is included for GeoJP2 (tm) (GeoTIFF-in-JPEG2000), 
ERDAS GML-in-JPEG2000, and the new GML-in-JPEG2000 specification developed
at OGC. <p>

Support for the JP2ECW driver in GDAL is optional, and requires linking
in external ECW SDK libraries provided by ERDAS.<p>

<h2>Creation Issues</h2>

The ECW 4.x SDK from ERDAS is only free for image decompression.  To 
compress images it is necessary to build with the read/write SDK and to 
provide an OEM licensing key at runtime which may be purchased from ERDAS.<p>

For those still using the ECW 3.3 SDK, images less than 500MB may be 
compressed for free, while larger images require licensing from ERDAS.  See
the licensing agreement and the LARGE_OK option.<p>

Creation Options:<p>

<ul>

<li> <b>TARGET=percent</b>: Set the target size reduction as a percentage of 
the original.  If not provided defaults to 75 for an 75% reduction.  TARGET=0 
uses lossless compression.<p>

<li> <b>PROJ=name</b>: Name of the ECW projection string to use. 
Common examples are NUTM11, or GEODETIC.<p>

<li> <b>DATUM=name</b>: Name of the ECW datum string to use. 
Common examples are WGS84 or NAD83.<p>

<li> <b>LARGE_OK=YES</b>: When built with the ECW 3.x SDK this option can be 
set to allow compressing files larger than 500MB.  It is the users 
responsibility to ensure that the licensing requirments for large file 
compression are being adhered to.<p>

<li> <b>ECW_ENCODE_KEY=key</b>: Provide the OEM encoding key purchased from 
Erdas which permits encoding images.  The key is is approximately 129 hex 
digits long.  It may also be provided globally as a configuration option.<p>

<li> <b>ECW_ENCODE_COMPANY=name</b>: Provide the name of the company ERDAS
issued the OEM encoding key (see ECW_ENCODE_KEY) to.  This must exactly match
the name used by ERDAS in issuing the OEM key.  It may also be provided 
globally as a configuration option.<p>

<li> <b>GMLJP2=YES/NO</b>: Indicates whether a GML box conforming to the OGC GML in JPEG2000 specification should be included in the file.  Defaults to YES.<p>

<li> <b>GeoJP2=YES/NO</b>: Indicates whether a UUID/GeoTIFF box conforming to the GeoJP2 (GeoTIFF in JPEG2000) specification should be included in the file.  Defaults to YES.<p>

<li> <b>PROFILE=profile</b>: One of BASELINE_0, BASELINE_1, BASELINE_2, 
NPJE or EPJE.  Review the ECW SDK documentation for details on profile 
meanings.<p>

<li> <b>PROGRESSION=LRCP/RLCP/RPCL</b>: Set the progression order with
which the JPEG2000 codestream is written.<p>

<li> <b>CODESTREAM_ONLY=YES/NO</b>: If set to YES, only the compressed
imagery code stream will be written.  If NO (the default) a JP2 package
will be written around the code stream including a variety of meta
information.<p>

<li> <b>LEVELS=n</b>: See ECW SDK for details.<p>
<li> <b>LAYERS=n</b>: See ECW SDK for details.<p>
<li> <b>PRECINCT_WIDTH=n</b>: See ECW SDK for details.<p>
<li> <b>PRECINCT_HEIGHT=n</b>: See ECW SDK for details.<p>
<li> <b>TILE_WIDTH=n</b>: See ECW SDK for details.<p>
<li> <b>TILE_HEIGHT=n</b>: See ECW SDK for details.<p>
<li> <b>INCLUDE_SOP=YES/NO</b>: See ECW SDK for details.<p>
<li> <b>INCLUDE_EPH=YES/NO</b>: See ECW SDK for details.<p>
<li> <b>DECOMPRESS_LAYERS=n</b>: See ECW SDK for details.<p>
<li> <b>DECOMPRESS_RECONSTRUCTION_PARAMETER=n</b>: See ECW SDK for details.<p>

</ul>

JPEG2000 format does not support creation of overviews since the format 
is already considered to be optimized for "arbitrary overviews". <P>

<h2> Configuration Options </h2>

The ERDAS ECW SDK supports a variety of 
<a href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">runtime configuration 
options</a> to control various features.  Most of these are exposed as GDAL 
configuration options.  See the ECW SDK documentation for full details on the
meaning of these options. 

<ul>
<li> <b>ECW_CACHE_MAXMEM=bytes</b>: maximum bytes of RAM used for in-memory 
caching.  If not set, up to one quarter of physical RAM will be used by the 
SDK for in-memory caching.<p>

<li> <b>ECW_TEXTURE_DITHER=TRUE/FALSE</b>: This may be set to FALSE to disable
dithering when decompressing ECW files.  Defaults to TRUE.<p>

<li> <b>ECW_FORCE_FILE_REOPEN=TRUE/FALSE</b>: This may be set to TRUE to 
force open a file handle for each file for each connection made.  Defaults to 
FALSE.<p>

<li> <b>ECW_CACHE_MAXOPEN=number</b>: The maximum number of files to keep 
open for ECW file handle caching.  Defaults to unlimited.<p>

<li> <b>ECW_AUTOGEN_J2I=TRUE/FALSE</b>: Controls whether .j2i index files 
should be created when opening jpeg2000 files.  Defaults to TRUE.<p>

<li> <b>ECW_RESILIENT_DECODING=TRUE/FALSE</b>: Controls whether the reader
should be forgiving of errors in a file, trying to return as much data as is
available.  Defaults to TRUE.  If set to FALSE an invalid file will result
in an error.<p>

<li> <b>ECW_ENCODE_KEY, ECW_ENCODE_COMPANY</b>: These values, as described
in the creation options, may also be set as configuration options. See above.
<p>


</ul>

<h2>See Also</h2>

<ul>
<li> Implemented as <tt>gdal/frmts/ecw/ecwdataset.cpp</tt>.<p>

<li> ECW SDK available at <a href="http://www.erdas.com/products/ERDASECWJPEG2000SDK/Details.aspx">erdas.com</a>.

<li> <a href="http://trac.osgeo.org/gdal/wiki/ECW">GDAL ECW Build Hints</a>
</ul>

</body>
</html>
